Docs/env vars contract ids custom rpc wallet flow - #324

Summary

Adds four pieces of previously-missing documentation:

• Every NEXT_PUBLIC_* environment variable the app actually reads, with purpose, type, and defaults
• The deployed contract IDs per network and how to override them (including hardcoded testnet
  defaults vs. empty mainnet defaults)
• A complete guide to running against a local or custom Soroban RPC, with failover behavior explained
• A full accounting of the wallet connection flow and all real Freighter failure modes the code
  handles (not installed, locked, wrong network, rejected)

Every documented claim was traced to actual source code, not written from general assumption.

Changes

#236 — docs: document every NEXT_PUBLIC_* environment variable

• Complete NEXT_PUBLIC_* inventory in docs/environment-variables.md: network config (default
  network, RPC URLs, fallback URLs), contract IDs (testnet with hardcoded defaults, mainnet requiring
  explicit setup), optional API URL, app metadata
• Cross-checked against lib/stellar.ts, lib/contracts.ts, lib/api.ts, next.config.mjs, and
  .github/workflows/web.yml
• Documented local vs. CI defaults (CI does not set these vars; app falls back to hardcoded defaults
  or public endpoints)

#237 — docs: document deployed contract IDs per network and override mechanism

• docs/environment-variables.md Contract IDs section: per-network values, required/optional
  status, hardcoded defaults for testnet, empty defaults for mainnet, and override mechanism for each
• Updated README with links to contract ID documentation in
  docs/environment-variables.md#contract-ids
• Documented why mainnet IDs default to empty (intentional safeguard against pointing at undeployed
  contracts)

#238 — docs: add README section on running against a local or custom RPC

• New file docs/custom-rpc.md: local quickstart (Soroban Docker), custom RPC provider setup, and
  failover URL configuration
• Explained actual failover behavior: 3 consecutive failures per URL, round-robin through list,
  wrapped by public default
• Included troubleshooting section for common issues (connection refused, high latency, contract not
  found)

#239 — docs: document wallet connection flow and Freighter failure modes

• New file docs/wallet-connection.md: connection flow diagram, detection → prompt → network sync
• All four real Freighter states the code handles: not installed, locked, wrong network, rejected
• Error boundary behavior, polling for account/network changes (8s interval, paused when tab hidden),
  session persistence via localStorage
• Summary table and testing guide for all states
• Traced to actual code: lib/freighter.ts, hooks/useWallet.tsx,
  components/wallet/ConnectButton.tsx

Test Plan

• Read docs/environment-variables.md end-to-end; verify every variable name matches code and
  defaults match hardcoded values in lib/stellar.ts and lib/contracts.ts
• Read docs/custom-rpc.md; verify failover threshold (3) matches
  lib/stellar.ts:FAILOVER_THRESHOLD
• Follow local RPC quickstart instructions; verify http://localhost:8000 works
• Read docs/wallet-connection.md; verify error messages match actual Freighter API strings in
  lib/freighter.ts
• Test wallet connection states locally if possible (not installed, locked, wrong network,
  rejected)

Closes #236, Closes #237, Closes #238, Closes #239